%% $Id$

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass[english]{article}
\usepackage[latin1]{inputenc}
\usepackage{babel}
\usepackage{verbatim}

%% do we have the `hyperref package?
\IfFileExists{hyperref.sty}{
   \usepackage[bookmarksopen,bookmarksnumbered]{hyperref}
}{}

%% do we have the `fancyhdr' or `fancyheadings' package?
\IfFileExists{fancyhdr.sty}{
\usepackage[fancyhdr]{latex2man}
}{
\IfFileExists{fancyheadings.sty}{
\usepackage[fancy]{latex2man}
}{
\usepackage[nofancy]{latex2man}
\message{no fancyhdr or fancyheadings package present, discard it}
}}

%% do we have the `rcsinfo' package?
\IfFileExists{rcsinfo.sty}{
\usepackage[nofancy]{rcsinfo}
\rcsInfo $Id$
\setDate{\rcsInfoLongDate}
}{
\setDate{2018/07/10}
\message{package rcsinfo not present, discard it}
}

\setVersionWord{Version:}  %%% that's the default, no need to set it.
\setVersion{=PACKAGE_VERSION=}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

\begin{Name}{1}{hpcprof-mpi}{The HPCToolkit Performance Tools}{The HPCToolkit Performance Tools}{hpcprof-mpi:\\ Analysis and Attribution of Call Path Performance Measurements}

\Prog{hpcprof-mpi} \emph{scalably} analyzes call path profile performance measurements (in parallel) and attributes them to static source code structure.
See \HTMLhref{hpctoolkit.html}{\Cmd{hpctoolkit}{1}} for an overview of \textbf{HPCToolkit}.

\end{Name}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Synopsis}

\Prog{hpcprof-mpi} \oOpt{options} \Arg{measurement-group}...

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Description}

\Prog{hpcprof-mpi} analyzes call path profile performance measurements,
attributes them to static source code structure,
and generates an experiment database for use with \HTMLhref{hpcviewer.html}{\Cmd{hpcviewer}{1}}
or  \HTMLhref{hpctraceviewer.html}{\Cmd{hpctraceviewer}{1}}.
\Prog{hpcprof-mpi} is especially designed for analyzing and attributing measurements
from large-scale executions.

\Prog{hpcprof} expects a list of \emph{measurement groups},
each of which is either a call path profile directory or an individual profile file.
For best results, two other options should be given:
\textbf{-I} to specify search directories for source code files
and \textbf{-S} to provide a source code structure file generated by \HTMLhref{hpcstruct.html}{\Cmd{hpcstruct}{1}}.
If no search directory arguments are given,
\Prog{hpcprof} will find only those source files that are specified via
either an absolute path still preseent in the file system
or a relative path w.r.t. the current working directory.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Arguments}

\begin{Description}
\item[\Arg{measurement-group}...] A sequence of file system paths,
each speciufying a call path profile directory or an individual profile file.
\end{Description}

Default values for an option's optional arguments are shown in \{\}.

\subsection{Options: Informational}

\begin{Description}

\item[\OptoArg{-v}{n}, \OptoArg{--verbose}{n}]
Print progress messages to stderr at verbosity level \Arg{n}.  \{1\}

\item[\Opt{-V}, \Opt{--version}]
Print version information.

\item[\Opt{-h}, \Opt{--help}]
Print help.

\item[\OptoArg{--debug}{n}]
Print debugging messages at level \Arg{n}. \{1\}

\end{Description}

\subsection{Options: Source Code and Static Structure}

\begin{Description}
\item[\OptArg{--name}{name}, \OptArg{--title}{name}]
Set the database's name (title) to \Arg{name}.

\item[\OptArg{-I}{dir}, \OptArg{--include}{dir}]
Use \Arg{dir} as a search directory to find source files.
For a recursive search, append a '+' after the last slash, e.g., \texttt{/mypath/+}.
This option may be given multiple times.

If a file appears in more than one search directory,
the ambiguity is resolved in favor of the search directory which occurred first on the command line.

\item[\OptArg{-S}{file}, \OptArg{--structure}{file}]
Use the structure file \Arg{file} produced by \HTMLhref{hpcstruct.html}{\Cmd{hpcstruct}{1}}
to identify source code elements for attribution of performance.
This option may be given multiple times,
e.g. to provide structure for shared libraries in addition to the application executable.

\item[\OptArg{-R}{'old-path=new-path'}, \OptArg{--replace-path}{'old-path=new-path'}]
Replace every instance of \Arg{old-path} by \Arg{new-path}
in all paths for which \Arg{old-path} is a prefix (e.g., in a profile's load map and source code).
Use '\Bs'\ to escape instances of '=' within a path.
This option may be given multiple times.
  
Use this option when a profile or binary contains references to files that have been relocated,
such as might occur with a file system change.
\end{Description}

\subsection{Options: Metrics}

\begin{Description}

\item[\OptArg{-M}{metric}, \OptArg{--metric}{metric}]
Compute the specified metrics, where \Arg{metric} is one of the following:
  \begin{itemize}
  \item[sum] Sum over threads/processes
  \item[stats] Sum, Mean, StdDev (standard deviation), CoefVar (coefficient of variation),
  Min, Max over threads/processes
  \item[thread] per-thread/process metrics
  \end{itemize}
Note that \Cmd{hpcprof-mpi}{1} cannot compute \Prog{thread}.

The default metric is \Prog{sum}.
This option may be given multiple times.

\item[\Opt{--force-metric}]
Show all thread-level metrics regardless of their number.

\item[\OptArg{--normalize}{all | none}]
If this option is \Prog{all}, normalize call paths in profiles to hide implementation details;
if \Prog{none}, do not normalize.
If not given, the default is \Prog{all}..

\end{Description}

\subsection{Options: Output}

\begin{Description}

\item[\OptArg{-o}{db-path}, \OptArg{--db}{db-path}, \OptArg{--output}{db-path}]
Write the computed experiment database to \Arg{db-path}.
The default path is \File{./hpctoolkit-$<$application$>$-database}.

\item[\OptArg{--metric-db}{yes | no}]
If \Prog{yes}, generate a thread-level metric value database for \Prog{hpcviewer} scatter plots.
The default is \Prog{yes}.

\item[\Opt{--remove-redundancy}]
Eliminate procedure name redundancy in output file \File{experiment.xml}.

\item[\Opt{--struct-id}]
Add 'str=nnn' field to profile data with the hpcstruct node id.
The default is \Prog{no}.

\end{Description}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Examples}

%\begin{enumerate}
%\item 


%\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\section{Notes}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{See Also}

\HTMLhref{hpctoolkit.html}{\Cmd{hpctoolkit}{1}}.\\
\HTMLhref{hpcprof-mpi.html}{\Cmd{hpcprof-mpi}{1}}.\\
\HTMLhref{hpcsummary.html}{\Cmd{hpcsummary}{1}}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Version}

Version: \Version

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{License and Copyright}

\begin{description}
\item[Copyright] \copyright\ 2002-2019, Rice University.
\item[License] See \File{README.License}.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Authors}

\noindent
Rice University's HPCToolkit Research Group \\
Email: \Email{hpctoolkit-forum =at= rice.edu} \\
WWW: \URL{http://hpctoolkit.org}.

\LatexManEnd

\end{document}

%% Local Variables:
%% eval: (add-hook 'write-file-hooks 'time-stamp)
%% time-stamp-start: "setDate{ "
%% time-stamp-format: "%:y/%02m/%02d"
%% time-stamp-end: "}\n"
%% time-stamp-line-limit: 50
%% End:
